Design System

AquaX — Current UI Design Baseline

Implementation alignment note: This document describes the design system currently used in code. It is not a future visual redesign. Where web and mobile differ, the difference is called out explicitly so future cleanup can standardize tokens without breaking current UI.

Table of Contents

1. Purpose And Scope
2. Current Technology Stack
3. Design Principles In Current Code
4. Brand And Visual Identity
5. Color System
6. Typography
7. Spacing, Radius, Shadow And Motion
8. Layout System
9. Components
10. Navigation Patterns
11. Status, Severity And Role Visuals
12. Forms And Inputs
13. Data Display
14. Feedback, Loading And Empty States
15. Icons And Assets
16. Responsive And Mobile Behavior
17. Accessibility Baseline
18. Implementation Guidelines
19. Current Design Debt
20. Traceability
21. Document History

1. Purpose And Scope

This document defines the UI design baseline for AquaX based on the current web and mobile codebase.

It covers:

• design tokens currently present in web and mobile;
• common colors, typography, spacing, radius, shadow and motion;
• shared component patterns used by the web dashboard and mobile app;
• role navigation and information architecture patterns;
• status/severity/role visuals;
• known inconsistencies that should be fixed in future design-system cleanup.

It does not introduce new product requirements. Feature scope remains governed by PRD, BRD, SRS, Product Backlog and Permission Matrix.

2. Current Technology Stack

Primary files:

3. Design Principles In Current Code

4. Brand And Visual Identity

Brand surfaces:

• Web sidebar brand: logo 44px, title AquaX, subtitle Hệ thống quản trị.
• Mobile app header: dark teal header #005D4E, logo container 36x36, brand text 20px / 700.
• Mobile launch loading: large logo 132px, white circular logo surface, green pulse/progress treatment.

5. Color System

5.1 Web Canonical CSS Variables

Web currently has the clearest token layer in variables.css.

Web also aliases these into Tailwind-friendly variables such as --primary, --muted, --border, --foreground, --destructive and --radius.

5.2 Mobile Theme Tokens

Mobile has a core/theme provider:

Current gap: Most production mobile screens use hardcoded Aqua/teal values such as #00796B, #006B5F, #007C6D, #005D4E, while core/theme.primary remains blue. Future cleanup should align core/theme to the AquaX teal palette before increasing token usage.

5.3 Current Palette From Code Usage

The following colors appear frequently and should be treated as current practical palette:

5.4 Status Color Guidance

6. Typography

6.1 Web Typography

Common web usage:

• Page title: 26px to 28px, bold, slate-950.
• Page subtitle: 16px to 18px, slate-600.
• Table header: 12px to 13px, bold, uppercase/tracking-wide.
• Card stat value: 30px, bold.
• Form label: 14px, medium.
• Input text: 16px.

6.2 Mobile Typography

Mobile theme exposes:

Common mobile screen usage:

Guideline: Use font weights intentionally. Current mobile code often uses 900; use it for labels/status/title emphasis, not long body text.

7. Spacing, Radius, Shadow And Motion

7.1 Spacing

Mobile core spacing:

Web spacing mostly uses Tailwind utilities:

Mobile layout constants:

7.2 Radius

Web variables:

Current usage:

• Web cards/tables/buttons/forms commonly use rounded-lg (8px).
• Mobile cards vary from 8px to 16px.
• Pills/badges use 999px.
• Mobile launch/logo and avatars use larger circular radii.

7.3 Shadow

7.4 Motion

Web motion tokens:

Current web supports:

• page settle animation;
• notification popover animation;
• view-transition animations;
• reduced-motion override.

Mobile supports:

• launch loading progress loop (1400ms);
• logo pulse (1100ms);
• standard React Navigation transitions.

8. Layout System

8.1 Web Layout

Current web application shell:

Web page composition:

1. Optional page header with title/subtitle/actions.
2. Filter/control row.
3. Stats grid or summary cards.
4. Table/list/detail cards.
5. Drawer/modal for contextual detail where needed.

8.2 Mobile Layout

Mobile shell:

Mobile tab bar:

• Active color: #00796B.
• Inactive color: #596274.
• Compact mode when width <390 or tabs.length >= 5.
• Height: 58/64px + safe-area bottom adjustment.
• Active indicator: teal top line.

9. Components

9.1 Web Reusable Components

Web component conventions:

• Prefer AntD for Button, Card, Table, Form, Input, Select, Drawer, Modal, Tag, Alert, Skeleton, Empty.
• Use Tailwind utilities for layout, spacing and specific overrides.
• Use CSS variables for primary, border, muted and shadow when possible.
• Use lucide-react icons in navigation/action buttons.

9.2 Mobile Reusable Components

Mobile component conventions:

• Use Pressable for tappable custom cards/list rows.
• Use StyleSheet.create locally for screen and component styling.
• Use lucide-react-native for icons.
• Use ActivityIndicator, RefreshControl, custom empty/error text and bottom sheets/modals for feedback.

10. Navigation Patterns

10.1 Web Navigation

Web uses APP_SHELL_NAV_ITEMS with role filters.

Current route groups:

Navigation item design:

• Height 44px.
• Rounded 8px.
• Icon 20px.
• Text 14px / 600.
• Active background currently bg-gray-300.
• Hover background slate-200.

10.2 Mobile Navigation

Mobile uses role-specific bottom tab configs:

Guidelines:

• Keep tab labels short enough for compact mode.
• Use icons from lucide-react-native.
• Register create/detail/edit screens as hidden tabs when they belong inside the role flow.
• Notification bell in header is currently available for OWNER and TECHNICIAN.

11. Status, Severity And Role Visuals

11.1 Health / Severity

Current mobile pond health colors:

Ticket severity/status currently uses config-driven chips in mobile/src/core/constants/ticket-configs.ts and AntD tags/buttons on web.

Guidelines:

• Pair color with text/icon, not color alone.
• Use short Vietnamese labels: Tốt, Cảnh báo, Nguy hiểm, Hoạt động, Vô hiệu hóa.
• Critical/danger should use red text and a light red background; avoid muted-only critical indicators.

11.2 Role Visuals

Mobile admin user cards currently use:

Web role labels:

12. Forms And Inputs

12.1 Web Forms

Current web form patterns:

Guidelines:

• Use existing constants from user-management-styles.ts for user-management forms.
• Prefer AntD validation and error states.
• Keep input heights stable to prevent layout shift.
• Use Vietnamese labels and errors consistently.

12.2 Mobile Forms

Current mobile form patterns:

• Inputs usually have light background #F8FAFC or white.
• Border color often #E2E8F0.
• Radius usually 12-14px.
• Placeholder/muted color #94A3B8.
• Error color #D60000 or #EF4444.
• Submit buttons use teal background and white bold text.

Guidelines:

• Use large touch targets, ideally 44px+.
• Preserve safe-area and keyboard behavior.
• Use bottom sheets/modals for action confirmation where current UX already does so.

13. Data Display

13.1 Web Tables

AquaTable is the preferred management table wrapper.

Current table style:

• Wrapped in AntD Card.
• Card radius 8px.
• Borderless card with --aquax-shadow-card.
• Header background --muted.
• Header text 12-13px, bold, tracking-wide.
• Cells px-4 py-4, larger on xl.
• Supports skeleton row loading to reduce layout jump.
• Supports small updating banner above table.

13.2 Web Cards And Stats

StatsGrid:

• Responsive grid: md:grid-cols-2, xl:grid-cols-4.
• Card radius 8px.
• Value size 30px.
• Tones: default/slate, primary/teal, warning/brown, danger/red.

13.3 Mobile Cards And Lists

Current card patterns:

Guidelines:

• Cards should be tappable with Pressable and accessibilityRole="button" where applicable.
• Important status should appear near title/top row.
• Use numberOfLines and flexible rows to avoid overflow.

14. Feedback, Loading And Empty States

14.1 Loading

14.2 Toasts And Messages

Mobile toast tones:

14.3 Empty / Error States

Current usage:

• Web uses AntD Empty, Alert, Skeleton.
• Mobile uses centered muted text, icon boxes and retry/back buttons.
• Error text is usually red; no-data text is slate/muted.

Guidelines:

• Empty state should state what is missing, not blame the user.
• Error state should include retry/back action when recoverable.
• Loading and updating states should preserve layout where possible.

15. Icons And Assets

Guidelines:

• Prefer lucide icons for action buttons and navigation.
• Icon size is commonly 18-24px; mobile header bell uses 26px.
• Pair unfamiliar icons with labels or tooltips where possible.
• Maintain stroke width around 2-2.4 for mobile; web around 1.9-2.2.

16. Responsive And Mobile Behavior

16.1 Web

Current responsive behavior:

• Sidebar becomes top mobile shell on small viewports.
• Desktop content uses sidebar offset and scrollable content area.
• Tables may use horizontal scrolling through AntD table scroll props where configured.
• Page headers stack vertically on small screens and align action buttons on larger screens.

Guidelines:

• Keep management UI dense but readable.
• Avoid fixed widths that break table/card content below 320px.
• Use responsive Tailwind utilities for spacing and grid columns.

16.2 Mobile

Current mobile behavior:

• Safe-area aware header/tab/content.
• Compact bottom tab mode for narrow screens and 5-tab roles.
• Pull-to-refresh on key owner home/data screens.
• Font shrinking for tab labels via adjustsFontSizeToFit.

Guidelines:

• Keep touch targets at least 44px.
• Use one-handed field workflows where possible.
• Avoid long tab labels.
• Use hidden stack screens inside tab navigators for detail/create/edit flows.

17. Accessibility Baseline

Current code includes some accessibility primitives:

• accessibilityRole="button" on mobile custom cards/buttons.
• aria-label on compact web navigation/sidebar toggle.
• Tooltips on compact web nav/toggle controls.
• Focus-visible styles on web sidebar controls.
• Reduced-motion media handling in web global styles.

Required improvements:

18. Implementation Guidelines

18.1 Web Guidelines

• Use AntD as base component system.
• Use ConfigProvider tokens for primary color, radius and font.
• Use variables.css tokens for colors/radius/shadow.
• Use Tailwind utilities for layout, spacing and one-off overrides.
• Use AquaTable for management tables.
• Use StatsGrid for standard stat summaries.
• Use AppShell navigation patterns for authenticated pages.
• Keep business logic out of reusable UI wrappers.

18.2 Mobile Guidelines

• Use RoleTabNavigator for role tab shells.
• Use Screen for new simple screens when applicable.
• Use AppToast for top-level feedback.
• Use AppButton when its current styling fits; otherwise document deviations.
• Prefer extracting repeated colors/styles into core/theme only after aligning theme tokens with current AquaX teal palette.
• Use Pressable with accessibility role for tappable custom cards.

18.3 Copy And Language

• Current UI is primarily Vietnamese.
• Use short operational labels:
  • Trang chủ
  • Trang trại
  • Ao nuôi
  • Nhật ký
  • Cá nhân
  • Hoạt động
  • Vô hiệu hóa
  • Cảnh báo
  • Nguy hiểm
• Keep button text command-oriented: Tạo, Lưu, Cập nhật, Gán, Đóng, Quay lại.

19. Current Design Debt

20. Traceability

21. Document History

End of Design System